Everything else being equal, you’d like your programs to run on as wide a variety of machines as possible, and exit gracefully (with an explanation) on the rest. The VideoToolbox is as portable as possible, given the Macintosh operating system traps that it uses. The driving force for compatibility has been TimeVideo, which has been tested on a wide variety of Macs, and now runs on any Mac with System 6.05 or better.
COMPUTER COMPATIBILITY:
Several colleagues have expressed interest in using this software on DOS PCs and Suns. Most of the routines are built upon QuickDraw, and therefore are only useful on Macs. However, several useful packages use nothing but Standard C and will work fine on any computer: Quick3 (LogLikelihood.c, MonotonicFit.c, PsychometricFit.c, etc.), Assign.c, BreakLines.c, VLambda.c, and all the statistical routines (randU.c, nrand.c, Binomial.c, ChiSquare.c, Mean.c, Normal.c, Shuffle.c, Uniform.c). The VideoToolbox.h header file defines a symbol "MAC_C" that is only true if the compiler supports the Macintosh extensions to C. For maximum portability of the VideoToolbox package, the Mac-dependent part of many of the files is only compiled if MAC_C is true. The luminance-control software in Luminance.c makes minimal use of GDHandles to designate particular video devices and load their cluts, and could be easily converted to work with some other scheme for designating video devices and loading their cluts.
Nearly all of the VideoToolbox now runs happily, natively, on 68k and PowerPC. In porting code from 68k to PowerPC Macs, Standard C is no problem. The tricky part arises only when you pass the address of a routine as an argument, and you can't be sure whether the routine will be called when the computer is running native or emulating a 68k. (Remember, much of the Apple Toolbox is still 68k code.) Apple developed a Mixed Mode Manager to deal with this. Hopefully you won't have to worry about it, since the VideoToolbox may already provide all the functionality you need. However, if you're interested, the following article spells out exactly what you need to do:
Radcliff, D. (1993) Making the leap to PowerPC. Develop 16:5-33. (Back issues of Develop can be ordered from APDA and are included as documents on the Developer CD-ROMs.)
COMPILER COMPATIBILITY:
I recommend that you use the latest version of Metrowerks CodeWarrior Gold C or Symantec THINK C; see "Advice". I suggest you get as much help as you can from the compiler by always enabling the strictest possible checking, especially the “Require prototypes” and “Check pointer types” options. In THINK C, set “\p is unsigned char *” (under “Compiler settings”). I also recommend using THINK C’s "universal" floating point format (i.e. don’t check “Native floating point format” under “Compiler settings”), because it allows all your projects, whether or not they use the 68881, to use the same ANSI library and precompiled header, and the speed and space penalty are negligible.
The Symantec THINK C, Apple MPW C, and Metrowerks CodeWarrior C compilers have a few minor differences.
1. THINK and MPW C support stdio printing of Pascal strings using the format "%#s", which is not part of Standard C. CodeWarrior C doesn't recognize that print format; you have to use c2pstr to convert your Pascal string to a C string and use the standard string format "%s".
2. The various compilers, including Apple's, offer a bewildering variety of names for two trivial, but much-used, routines to convert back and forth between C and Pascal strings. I suggest that you standardize on "c2pstr and p2cstr", which are currently defined in Apple's Strings.h. VideoToolbox.h has various conditionals to deal with older header files, to make sure that these names will always work. I suggest you use the preferred (lower case) routine names in place of the older (mixed case) names: C2PStr, CtoPstr, P2CStr, and PtoCstr.
3. CodeWarrior and THINK C have unique incompatible schemes for including assembly code in C files. (Unfortunately, Standard C does not specify a standard way to do this.) MPW C will only allow machine code (i.e. numbers). This affects SetEntriesQuickly.c. Assembly code is processor specific, so I suggest avoiding it.
4. When compiling for 68k machines, THINK and CodeWarrior C allow you to specify the size of int to be either 2 ("short") or 4 bytes (long). MPW C sets it to 4 bytes (long). On PowerPC an int is always 4 bytes. When it matters, you should explicitly declare your variables as “short” or “long” rather than just “int”.
5. All three compilers have some support for a console window for stdout and stdin. But MPW's is rudimentary. THINK C and CodeWarrior both have useful consoles.
PASCAL:
The VideoToolbox can be made into a Pascal-callable library fairly easily. You just add the prefix "pascal" to all the function declarations and compile it into a library, which I understand you can then call from Pascal. However, I've never tried this.
SYSTEM COMPATIBILITY:
In general, I recommend using the latest System software. Everything runs fine under Systems 6 and 7, and is compatible with 32-bit mode and virtual memory. (I haven't tried System 7.5 yet, but don't anticipate any incompatibility.) None of the demos is “MultiFinder friendly”. They’re compatible with MultiFinder, but they all hog the machine, which I think is perfectly proper for experiments. If you want to, it would be easy to make the programs polite by adding calls to using WaitNextEvent(), following Apple’s guidelines in the "New Inside Macintosh: Memory" book.
VIDEO CARD COMPATIBILITY:
All Macintosh video cards and built-in video devices come with video drivers that conform sufficiently well to the Apple guidelines that they are compatible with the VideoToolbox, but they may be much slower than you’d guess. This is discussed in the documents “Video synch” and “Video bugs”. You should check out your video drivers by running the self-explanatory demo TimeVideo. (You might also want to try the more arcane demo TestGDVideo, which assumes familiarity with Apple’s Designing Cards and Drivers book.)
REQUIRE. The VideoToolbox routine Require.c will check for any required cpu, floating point chip, and level of QuickDraw and quits with an explanation if they’re absent. Minimally, if your program uses Color QuickDraw (e.g. if your program uses a GDHandle) then your program should begin by calling Require(gestalt8BitQD). If you use the New Palette Manager, e.g. SetDepth, then you should use Gestalt() to require System 6.05 or better. However, offscreen GWorlds are very handy and require 32-bit QuickDraw, so for most people I’d suggest just calling Require(gestalt32BitQD). That’s enough to guarantee availability of all the QuickDraw traps in Inside Mac I-VI, except that GetPixBaseAddr() gave wrong answers in early versions of 32-bit QuickDraw, so use the VideoToolbox routine GetPixBaseAddr32() instead, in RectToAddress.c.
PIXELSIZE. Your programs should not assume any particular screen depth or size. Instead you should get them from the screen’s GDHandle, which I like to call “device”:
device=GetScreenDevice(1);
pixelSize=(**(**device).gdPMap).pixelSize;
colors=GDColors(device); // number of different colors that can be displayed
clutSize=GDClutSize(device); // number of rgb entries in the clut
rect=(*device)->gdRect; // in global coordinates
type=(*device)->gdType; // value is one of: clutType, directType, or fixedType
It’s useful to check the current device “type”; type==clutType indicates that each pixel is wholly transformed by a single programmable color lookup table; type==fixedType has a similar meaning except that the color lookup table cannot be changed; type==directType indicates that each pixel is broken up into three components that are individually transformed by three programmable lookup tables. The clutSize is always less than or equal to 256. (It’s 1<<pixelSize unless you’re in 16- or 32-bit mode, i.e. type==directType, in which case the clutSize will be 32 or 256, since the clut is then treated as three separate 32- or 256-entry lookup tables. A 16-bit pixel is broken up into three 5-bit indices, discarding the highest bit; a 32-bit pixel is broken up into three 8-bit indices, discarding the highest 8 bits.) If you prefer a particular screen depth you can try to get it by calling HasDepth() and SetDepth(), which are documented in Inside Mac VI. (Note that HasDepth and SetDepth are part of the “New” Palette Manager, which will be present only if you have Color QuickDraw and the System is at least 6.05 or you have 32-bit QuickDraw.)
24/32-bit ADDRESSING. When debugging, it’s convenient to set your Mac to 32-bit addressing (use the Memory Control Panel) since this allows the THINK C Debugger to work always, even in sections of code that are surrounded by calls to SwapMMUMode. However, bear in mind that in this congenial 32-bit addressing environment, SwapMMUMode and StripAddress don’t do anything. It’s easy to forget to call StripAddress on all the RAM addresses that you access in 32-bit-addressing mode. You may not discover such bugs in your program until you run it on a Mac set to 24-bit addressing.
